--------------------------
LTVT Image Grabber v_1.8.2
--------------------------

This is a simple utility for automatically downloading a set 
of images from the internet, intended for use with the 
freeware Lunar Terminator Visualization Tool:

http://ltvt.wikispaces.com/Image+Grabber

The images to be downloaded can be specified by providing a list 
of URL's, or by specifying a numerical pattern for sequentially 
numbered files.

All images downloaded in a given run are stored in a 
single user-selectable folder, even if they come from 
different directories on the internet.

As it runs, the program lists each URL it attempts to access.
If successful, the location of the downloaded file is displayed,
otherwise an error message is displayed and the program proceeds
to the next URL in the list.  

There are three different modes of operation, selectable by
clicking the tabs near the top of the screen.  

In Mode 2, when a text file of existing LTVT calibration data 
for lunar images is available, that information is automatically 
copied, for each image successfully downloaded, to a new calibration 
data file which includes the name and directory on the local hard 
drive under which the image was stored.  This file can be used to
directly access the images with LTVT, or the lines generated can be
cut and pasted into an existing calibration file.

Note that the program includes a "Test mode" which makes the program
act as if each image had been successfully retrieved WITHOUT actually
attempting to retrieve them from the internet.  

It also has an "Abort" button to halt the sequencing through the list.  
Note than an abort request will be processed only AFTER the current 
download is complete. There is no way to halt the current file transfer 
other than terminating the Image Grabber with a system command such as  
through the Windows Task Manager or with CRTL-ALT-DEL. Because data is 
saved at each step, no successful work will be lost, but the Image Grabber
will have to be restarted.  A file that causes a consistent problem can
be commented out of the URL by using any simple text editor to place an 
asterisk (*) at the start of the line on which the offending URL is listed,
or the line can be deleted entirely.


------------------------
1. Specifying a URL List
------------------------

The URL list is a simple text file listing the image URL's.
It can have any name and extension.

Blank lines and lines with an asterisk (*) in column 1 are ignored
unless the line begins with the sequence "*URL:" (case-insensitive,
but without the quotes) in which case the text following *URL: is 
taken as the URL, just as if it appeared without this prefixing text
(this feature allows embedding URL's as comments in LTVT "calibration"
files -- see item 2, below).

The image URL can be followed by a comma and a substitute filename.
If a substitute filename is specified, the file will be stored under
that name, otherwise it will be stored under the same name as that
with which it was retrieved.

To accomodate the possibility that the URL and/or desired substitute 
filename may themselves contain commas, the URL and substitute filename
are regarded as "fields" of a comma-separated-values (CSV) text list.  
In accordance with the normal rules for CSV input, a field with internal
commas will be properly read if the entire field is begun and end with a
double-quote symbol (").  It can also contain any number of internal 
double-quote symbols if each of those is repeated twice.

As an example:

"http://www.mysite.com/images/July 4, 2011 ""funny"" moon.jpg", testfile.jpg

is read as a request to download --

  the file:  http://www.mysite.com/images/July 4, 2011 "funny" moon.jpg 
  and save it as:  testfile.jpg 

Without the beginning and ending quotes it would be read as a request to download --

  the file:  http://www.mysite.com/images/July 4
  and save it as:  2011 ~~funny~~ moon.jpg

(note that in the output file name ImageGrabber substitutes ~ for the " because the
latter is an illegal character for Windows file names) 


---------------------------------------------
2. Specifying an LTVT Cal File and a URL List
---------------------------------------------

This method is more complicated, but (once mastered) it provides
an efficient way of exchanging LTVT image calibration information.

It requires two input files:

1. A normal LTVT calibration data file ("cal file"), which refers to 
image files stored at specific locations on a local disk drive.

2. A list of URL's from which fresh copies of the same images can be
retrieved from the internet.  This is identical in format to the URL
list described in the previous instance.  It can include a substitute
name (separated from the URL by a comma), so that an image file stored
on the internet under one name can be downloaded to disk under a 
different name matching the one used in the cal file.

Lines starting with the "*URL:" sequence described above can be used
to intersperse calibration and URL information in a single file, and
single file can be used as inputs (1) AND (2).

In the Cal File + URL List mode, the program reads each line of calibration 
data and sees if a matching file name can be found in the URL list.  If such
a file is found, it is downloaded and new calibration lines are prepared,
incorporating the original calibration information, but pointing to the
folder in which the fresh image from the internet was stored.  The user
is free to specify the file to which the new calibration lines should
be written.  This can be a new file or an existing one. If it is an 
existing file name, it can either be replaced the new data lines can be
appended to it. In the appending mode, only the new data lines are
written, with no spaces between them.  Otherwise the comments and 
headings in the input calibration data file are echoed to the output
file.  The new calibration data lines can always be pasted into any 
other calibration file.

Because LTVT is only capable of loading files in .JPG and .BMP format,
and because the original files available on the internet may be in
different format (.GIF, .TIF, .PNG, etc.), the Image Grabber will 
download a file of the same name found in the URL list even if the 
extension is different.  In such cases, a message appears in the
output screen warning the user that they will need to manually convert
the downloaded file to and LTVT-readable image type, and will also
need to manually correct the automatically generated calibration data 
file if the final type is different from the one specified there.

In cases where the URL list specifies an LTVT-readable format file
(.BMP or .JPG), the Image Grabber will write the new calibration data
using the type of the retrieved file.  A note appears on the screen
if this is different from the image type used for the original
calibration. Warning messages also appear if the program is unable to 
locate anything corresponding to the calibrated image in the URL list.

Only the calibration data for the successfully downloaded images is
transferred to the new cal data file.

NOTE:  the present distribution contains a "Test Folder" with a
small set of calibration data and a corresponding URL list.  For
test purposes, no URL is provided for one of the calibrated images;
two of the images are downloaded under names differing from the ones
by which they are stored on the internet; and one of them has a file
type extension different than that specified in the cal file. All
except the first (for which no web address is given) should download
successfully.


--------------------------------
3. Specifying a Numeric Sequence
--------------------------------

Many images are stored with sequential file numbers.  In situations
of this sort, the program can download the images using automatically
generated URLs.  The user is asked to specify both the original file
names and the names under which the downloaded files should be stored.

Example:

Medium resolution versions of the Metric images from Apollo 15 are
stored at URL's of the form:

http://www.lpi.usra.edu/resources/apollo/images/print/AS15/M/0100.jpg

The changing numeric part is the "0100", which is always a 4-digit 
number with leading zeroes.

The user specifies:

1. The part preceding the number "0100" :

  http://www.lpi.usra.edu/resources/apollo/images/print/AS15/M/

2. The part following the number "0100" :

  .jpg

and the same for the downloaded files.  For example, the downloads might
be named using:

1. Before the  "0100" :

   AS15-M-

2. After the "0100" :
  
  .jpg

This would cause the downloaded file corresponding to the automatically
generated URL in the present example to be called "AS15-M-0100.jpg"

--

On some sites, the numeric part is not padded to a fixed length with 
leading zeros. In that case, specify the "number of digits" as zero and 
the program will generate unpadded numbers with just the number of digits 
required to accomodate the number at hand.


--------------------------
Additional Instructions
--------------------------

Pointing the mouse at any of the controls in the program window should
provide a brief "Tool Tip" explanation of what they do.

Although intended for downloading images, the program can be used to
download files of any extension, including *.htm or *.html (which will
be stored as the source code).  This can be useful, for example, for
collecting the support information that goes with the Apollo images.


----------
DISCLAIMER
----------

Image Grabber is meant to facilitate the manual downloading of a
list of files freely accessible to the user over the internet.  
The providers of some files may well have a copyright that 
restricts their use to personal viewing/access by the user.  
Files collected with Image Grabber should be regarded in the 
same way as files manually downloaded from the internet, and
should not be used in ways unintended by their provider.

The author of Image Grabber assumes no responsibility express or
implied for problems arising from the use or presence of files
downloded with it.

           -- Jim Mosher (jimmosher@yahoo.com,  February 3, 2012)

